---
id: get-dataset
title: "Retrieve a dataset"
description: "Returns a dataset."
sidebar_label: "Retrieve a dataset"
hide_title: true
hide_table_of_contents: true
api:
  {
    "operationId": "getDataset",
    "description": "Returns a dataset.",
    "tags": ["Datasets"],
    "responses":
      {
        "200":
          {
            "description": "OK",
            "content":
              {
                "application/json":
                  {
                    "schema":
                      {
                        "type": "object",
                        "properties":
                          {
                            "id":
                              {
                                "type": "object",
                                "description": "The ID of the dataset.",
                                "properties":
                                  {
                                    "namespace":
                                      {
                                        "type": "string",
                                        "description": "The namespace of the dataset.",
                                      },
                                    "name":
                                      {
                                        "type": "string",
                                        "description": "The name of the dataset.",
                                      },
                                  },
                                "title": "DatasetId",
                              },
                            "type":
                              {
                                "description": "The type of the dataset.",
                                "type": "string",
                              },
                            "name":
                              {
                                "description": "The **logical** name of the dataset.",
                                "type": "string",
                              },
                            "physicalName":
                              {
                                "description": "The **physical** name of the dataset.",
                                "type": "string",
                              },
                            "createdAt":
                              {
                                "description": "An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the date/time the dataset was created.",
                                "type": "string",
                                "format": "date-time",
                              },
                            "updatedAt":
                              {
                                "description": "An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the date/time the dataset was updated.",
                                "type": "string",
                                "format": "date-time",
                              },
                            "namespace":
                              {
                                "type": "string",
                                "description": "The namespace of the dataset.",
                              },
                            "sourceName":
                              {
                                "description": "The name of the source associated with the dataset.",
                                "type": "string",
                              },
                            "fields":
                              {
                                "description": "The fields of the dataset.",
                                "type": "array",
                                "items":
                                  {
                                    "type": "object",
                                    "properties":
                                      {
                                        "name":
                                          {
                                            "description": "The name of the field.",
                                            "type": "string",
                                          },
                                        "type":
                                          {
                                            "description": "The data type of the field.",
                                            "type": "string",
                                          },
                                        "tags":
                                          {
                                            "description": "List of tags.",
                                            "type": "array",
                                            "items": { "type": "string" },
                                          },
                                        "description":
                                          {
                                            "description": "The description of the field.",
                                            "type": "string",
                                          },
                                      },
                                    "required": ["name", "type"],
                                  },
                              },
                            "tags":
                              {
                                "description": "List of tags.",
                                "type": "array",
                                "items": { "type": "string" },
                              },
                            "lastModifiedAt":
                              {
                                "description": "An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the date/time the dataset was last modified by a successful run.",
                                "type": "string",
                                "format": "date-time",
                              },
                            "lastLifecycleState":
                              {
                                "description": "The last lifecycle state of the dataset.",
                                "type": "string",
                              },
                            "description":
                              {
                                "description": "The description of the dataset.",
                                "type": "string",
                              },
                            "facets":
                              {
                                "description": "The facets of the dataset. For a full list of standard dataset facets, see [OpenLineage](https://github.com/OpenLineage/OpenLineage/blob/main/spec/OpenLineage.md#standard-facets).",
                                "type": "object",
                                "additionalProperties":
                                  {
                                    "description": "A custom facet enables the extension of _dataset_, _job_, and _run_ metadata. A custom facet **must** also have a schema, where a version of the schema is identifiable via a URL. A field within the schema **must** not start with an underscore (`_`).",
                                    "allOf":
                                      [
                                        {
                                          "description": "All base facet fields are prefixed with an underscore (`_`) to avoid field naming conflicts defined with other facets.",
                                          "type": "object",
                                          "properties":
                                            {
                                              "_producer":
                                                {
                                                  "description": "URI identifying the producer of this metadata. For example this could be a git url with a given tag or sha",
                                                  "type": "string",
                                                  "format": "uri",
                                                  "example": "https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/client",
                                                },
                                              "_schemaURL":
                                                {
                                                  "description": "The URL to the corresponding version of the schema definition following a $ref URL Reference (see https://swagger.io/docs/specification/using-ref/)",
                                                  "type": "string",
                                                  "format": "uri",
                                                  "example": "https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/spec/OpenLineage.yml#MyCustomJobFacet",
                                                },
                                            },
                                          "required":
                                            ["_producer", "_schemaURL"],
                                          "title": "BaseFacet",
                                        },
                                        {
                                          "type": "object",
                                          "additionalProperties": true,
                                        },
                                      ],
                                    "title": "CustomFacet",
                                  },
                                "title": "DatasetFacets",
                              },
                            "currentVersion":
                              {
                                "description": "The current version of the dataset.",
                                "type": "string",
                                "format": "uuid",
                              },
                            "deleted":
                              {
                                "description": "The deleted state of the dataset.",
                                "type": "boolean",
                              },
                          },
                        "example":
                          {
                            "id":
                              {
                                "namespace": "my-namespace",
                                "name": "my-dataset",
                              },
                            "type": "DB_TABLE",
                            "name": "my-dataset",
                            "physicalName": "public.mytable",
                            "createdAt": "2019-05-09T19:49:24.201361Z",
                            "updatedAt": "2019-05-09T19:49:24.201361Z",
                            "namespace": "my-namespace",
                            "sourceName": "my-source",
                            "fields":
                              [
                                { "name'": "a", "type": "INTEGER", "tags": [] },
                                {
                                  "name'": "b",
                                  "type": "TIMESTAMP",
                                  "tags": [],
                                },
                                { "name'": "c", "type": "INTEGER", "tags": [] },
                                { "name'": "d", "type": "INTEGER", "tags": [] },
                              ],
                            "tags": [],
                            "lastModifiedAt": null,
                            "description": "My first dataset!",
                            "facets": {},
                            "currentVersion": "b1d626a2-6d3a-475e-9ecf-943176d4a8c6",
                          },
                        "title": "Dataset",
                      },
                  },
              },
          },
      },
    "parameters":
      [
        {
          "name": "namespace",
          "in": "path",
          "description": "The name of the namespace.",
          "required": true,
          "schema":
            { "type": "string", "maxLength": 1024, "example": "my-namespace" },
        },
        {
          "name": "dataset",
          "in": "path",
          "description": "The name of the dataset.",
          "required": true,
          "schema":
            { "type": "string", "maxLength": 1024, "example": "my-dataset" },
        },
      ],
    "method": "get",
    "path": "/namespaces/{namespace}/datasets/{dataset}",
    "servers":
      [
        {
          "url": "http://localhost:5000/api/v1",
          "description": "Local API server",
        },
      ],
    "info":
      {
        "title": "Marquez",
        "version": "0.50.0",
        "description": "Marquez is an open source **metadata service** for the **collection**, **aggregation**, and **visualization** of a data ecosystem's metadata.",
        "license":
          {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html",
          },
      },
    "postman":
      {
        "name": "Retrieve a dataset",
        "description":
          { "content": "Returns a dataset.", "type": "text/plain" },
        "url":
          {
            "path": ["namespaces", ":namespace", "datasets", ":dataset"],
            "host": ["{{baseUrl}}"],
            "query": [],
            "variable":
              [
                {
                  "disabled": false,
                  "description":
                    {
                      "content": "(Required) The name of the namespace.",
                      "type": "text/plain",
                    },
                  "type": "any",
                  "value": "",
                  "key": "namespace",
                },
                {
                  "disabled": false,
                  "description":
                    {
                      "content": "(Required) The name of the dataset.",
                      "type": "text/plain",
                    },
                  "type": "any",
                  "value": "",
                  "key": "dataset",
                },
              ],
          },
        "header": [{ "key": "Accept", "value": "application/json" }],
        "method": "GET",
      },
  }
sidebar_class_name: "get api-method"
info_path: docs/api/marquez
custom_edit_url: null
---

import ApiTabs from "@theme/ApiTabs";
import MimeTabs from "@theme/MimeTabs";
import ParamsItem from "@theme/ParamsItem";
import ResponseSamples from "@theme/ResponseSamples";
import SchemaItem from "@theme/SchemaItem";
import SchemaTabs from "@theme/SchemaTabs";
import DiscriminatorTabs from "@theme/DiscriminatorTabs";
import TabItem from "@theme/TabItem";

## Retrieve a dataset

Returns a dataset.

<details style={{"marginBottom":"1rem"}} data-collapsed={false} open={true}><summary style={{}}><strong>Path Parameters</strong></summary><div><ul><ParamsItem className={"paramsItem"} param={{"name":"namespace","in":"path","description":"The name of the namespace.","required":true,"schema":{"type":"string","maxLength":1024,"example":"my-namespace"}}}></ParamsItem><ParamsItem className={"paramsItem"} param={{"name":"dataset","in":"path","description":"The name of the dataset.","required":true,"schema":{"type":"string","maxLength":1024,"example":"my-dataset"}}}></ParamsItem></ul></div></details><div><ApiTabs><TabItem label={"200"} value={"200"}><div>

OK

</div><div><MimeTabs schemaType={"response"}><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>id</strong><span style={{"opacity":"0.6"}}> object</span></summary><div style={{"marginLeft":"1rem"}}><div style={{"marginTop":".5rem","marginBottom":".5rem"}}>

The ID of the dataset.

</div><SchemaItem collapsible={false} name={"namespace"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The namespace of the dataset."}}></SchemaItem><SchemaItem collapsible={false} name={"name"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The name of the dataset."}}></SchemaItem></div></details></SchemaItem><SchemaItem collapsible={false} name={"type"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"description":"The type of the dataset.","type":"string"}}></SchemaItem><SchemaItem collapsible={false} name={"name"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"description":"The **logical** name of the dataset.","type":"string"}}></SchemaItem><SchemaItem collapsible={false} name={"physicalName"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"description":"The **physical** name of the dataset.","type":"string"}}></SchemaItem><SchemaItem collapsible={false} name={"createdAt"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"description":"An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the date/time the dataset was created.","type":"string","format":"date-time"}}></SchemaItem><SchemaItem collapsible={false} name={"updatedAt"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"description":"An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the date/time the dataset was updated.","type":"string","format":"date-time"}}></SchemaItem><SchemaItem collapsible={false} name={"namespace"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The namespace of the dataset."}}></SchemaItem><SchemaItem collapsible={false} name={"sourceName"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"description":"The name of the source associated with the dataset.","type":"string"}}></SchemaItem><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>fields</strong><span style={{"opacity":"0.6"}}> object[]</span></summary><div style={{"marginLeft":"1rem"}}><div style={{"marginTop":".5rem","marginBottom":".5rem"}}>

The fields of the dataset.

</div><li><div style={{"fontSize":"var(--ifm-code-font-size)","opacity":"0.6","marginLeft":"-.5rem","paddingBottom":".5rem"}}>Array [</div></li><SchemaItem collapsible={false} name={"name"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"description":"The name of the field.","type":"string"}}></SchemaItem><SchemaItem collapsible={false} name={"type"} required={true} schemaName={"string"} qualifierMessage={undefined} schema={{"description":"The data type of the field.","type":"string"}}></SchemaItem><SchemaItem collapsible={false} name={"tags"} required={false} schemaName={"string[]"} qualifierMessage={undefined} schema={{"description":"List of tags.","type":"array","items":{"type":"string"}}}></SchemaItem><SchemaItem collapsible={false} name={"description"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"description":"The description of the field.","type":"string"}}></SchemaItem><li><div style={{"fontSize":"var(--ifm-code-font-size)","opacity":"0.6","marginLeft":"-.5rem"}}>]</div></li></div></details></SchemaItem><SchemaItem collapsible={false} name={"tags"} required={false} schemaName={"string[]"} qualifierMessage={undefined} schema={{"description":"List of tags.","type":"array","items":{"type":"string"}}}></SchemaItem><SchemaItem collapsible={false} name={"lastModifiedAt"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"description":"An [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp representing the date/time the dataset was last modified by a successful run.","type":"string","format":"date-time"}}></SchemaItem><SchemaItem collapsible={false} name={"lastLifecycleState"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"description":"The last lifecycle state of the dataset.","type":"string"}}></SchemaItem><SchemaItem collapsible={false} name={"description"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"description":"The description of the dataset.","type":"string"}}></SchemaItem><SchemaItem collapsible={true} className={"schemaItem"}><details style={{}}><summary style={{}}><strong>facets</strong><span style={{"opacity":"0.6"}}> object</span></summary><div style={{"marginLeft":"1rem"}}><div style={{"marginTop":".5rem","marginBottom":".5rem"}}>

The facets of the dataset. For a full list of standard dataset facets, see [OpenLineage](https://github.com/OpenLineage/OpenLineage/blob/main/spec/OpenLineage.md#standard-facets).

</div><SchemaItem collapsible={false} name={"description"} required={false} schemaName={""} qualifierMessage={undefined} schema={"A custom facet enables the extension of _dataset_, _job_, and _run_ metadata. A custom facet **must** also have a schema, where a version of the schema is identifiable via a URL. A field within the schema **must** not start with an underscore (`_`)."}></SchemaItem><SchemaItem collapsible={false} name={"allOf"} required={false} schemaName={""} qualifierMessage={undefined} schema={[{"description":"All base facet fields are prefixed with an underscore (`_`) to avoid field naming conflicts defined with other facets.","type":"object","properties":{"_producer":{"description":"URI identifying the producer of this metadata. For example this could be a git url with a given tag or sha","type":"string","format":"uri","example":"https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/client"},"_schemaURL":{"description":"The URL to the corresponding version of the schema definition following a $ref URL Reference (see https://swagger.io/docs/specification/using-ref/)","type":"string","format":"uri","example":"https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/spec/OpenLineage.yml#MyCustomJobFacet"}},"required":["_producer","_schemaURL"],"title":"BaseFacet"},{"type":"object","additionalProperties":true}]}></SchemaItem><SchemaItem collapsible={false} name={"title"} required={false} schemaName={""} qualifierMessage={undefined} schema={"CustomFacet"}></SchemaItem></div></details></SchemaItem><SchemaItem collapsible={false} name={"currentVersion"} required={false} schemaName={"uuid"} qualifierMessage={undefined} schema={{"description":"The current version of the dataset.","type":"string","format":"uuid"}}></SchemaItem><SchemaItem collapsible={false} name={"deleted"} required={false} schemaName={"boolean"} qualifierMessage={undefined} schema={{"description":"The deleted state of the dataset.","type":"boolean"}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"id\": {\n    \"namespace\": \"my-namespace\",\n    \"name\": \"my-dataset\"\n  },\n  \"type\": \"DB_TABLE\",\n  \"name\": \"my-dataset\",\n  \"physicalName\": \"public.mytable\",\n  \"createdAt\": \"2019-05-09T19:49:24.201361Z\",\n  \"updatedAt\": \"2019-05-09T19:49:24.201361Z\",\n  \"namespace\": \"my-namespace\",\n  \"sourceName\": \"my-source\",\n  \"fields\": [\n    {\n      \"name'\": \"a\",\n      \"type\": \"INTEGER\",\n      \"tags\": []\n    },\n    {\n      \"name'\": \"b\",\n      \"type\": \"TIMESTAMP\",\n      \"tags\": []\n    },\n    {\n      \"name'\": \"c\",\n      \"type\": \"INTEGER\",\n      \"tags\": []\n    },\n    {\n      \"name'\": \"d\",\n      \"type\": \"INTEGER\",\n      \"tags\": []\n    }\n  ],\n  \"tags\": [],\n  \"lastModifiedAt\": null,\n  \"description\": \"My first dataset!\",\n  \"facets\": {},\n  \"currentVersion\": \"b1d626a2-6d3a-475e-9ecf-943176d4a8c6\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem></ApiTabs></div>

